Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:Scroller;,Scroller

Inherits From:	Control : View : Responder : Object

Declared In:	appkit/Scroller.h

Class Description

The Scroller class defines a Control that's used by a ScrollView object to position a document that's too large to be displayed in its entirety within a View.  A Scroller is typically represented on the screen by a bar, a knob, and two scroll buttons, although it may contain only some of these.  The knob indicates both the position within the document and the amount displayed relative to the size of the document.  The bar is the rectangular region that the knob slides within.  The scroll buttons allow the user to scroll in small increments by clicking, or in large increments by Alternate-clicking.  In discussions of the Scroller class, a small increment is referred to as a ªline incrementº (even if the Scroller is oriented horizontally), and a large increment is referred to as a ªpage increment,º although a page increment actually advances the document by one windowful.  When you create a Scroller, you can specify either a vertical or a horizontal orientation.

As a Control, a Scroller handles mouse events and sends action messages to its target (usually its parent ScrollView) to implement user-controlled scrolling.  The Scroller must also respond to messages from a ScrollView to represent changes in document positioning.

Scroller is a public class primarily for programmers who decide not to use a ScrollView but want to present a consistent user interface.  Its use is not encouraged except in cases where the porting of an existing application is made more straightforward.  In these situations, you initialize a newly created Scroller with initFrame:.  Then, you use setTarget: (Control) to set the object that will receive messages from the Scroller, and you use setAction: (Control) to specify the message that will be sent to the target by the Scroller.  When your target receives a message from the Scroller, it will probably need to query the Scroller using the hitPart and floatValue methods to determine what action to take.

The Scroller class has several constants referring to the parts of a Scroller.  A scroll button with an up arrow (or left arrow, if the Scroller is oriented horizontally) is known as a ªdecrement lineº button if it receives a normal click, and as a ªdecrement pageº button if it receives an Alternate-click.  Similarly, a scroll button with a down or right arrow functions as both an ªincrement lineº button and an ªincrement pageº button.  The constants defining the parts of a Scroller are as follows:

Constant	Refers To

NX_NOPART	No part of the Scroller
NX_KNOB	The knob
NX_DECPAGE	The button that decrements a page (up, left arrow)
NX_INCPAGE	The button that increments a page (down, right arrow)
NX_DECLINE	The button that decrements a line (up, left arrow)
NX_INCLINE	The button that increments a line (down, right arrow)
NX_KNOBSLOT  or	The bar
NX_JUMP

Instance Variables

float curValue;

float perCent;

int hitPart;

id target;

SEL action;

struct _sFlags{
	unsigned int isHoriz:1;
	unsigned int arrowsLoc:2;
	unsigned int partsUsable:2;

} sFlags;

curValue 	The position of the knob, from 0.0 (top or left position) to 1.0.

perCent 	The fraction of the bar the knob fills, from 0.0 to 1.0.

hitPart 	Which part got the last mouse-down event.

target 	The target of the Scroller.

action 	The action sent to Scroller's target.

sFlags.isHoriz 	True if this is a horizontal Scroller.

sFlags.arrowsLoc 	The location of the scroll buttons within the Scroller.

sFlags.partsUsable	The parts of the Scroller that are currently displayed.

Method Types

Initializing a Scroller	- initFrame:

Laying out the Scroller	- calcRect:forPart: 
- checkSpaceForParts
- setArrowsPosition:

Setting Scroller values	- floatValue
- setFloatValue: 
- setFloatValue::

Resizing the Scroller	- sizeTo::

Displaying	- drawArrow:: 
- drawKnob
- drawParts
- drawSelf:: 
- highlight:

Target and action	- setAction: 
- action
- setTarget: 
- target

Handling events	- acceptsFirstMouse
- hitPart
- mouseDown: 
- testPart: 
- trackKnob: 
- trackScrollButtons:

Archiving	- awake
- read: 
- write:

Instance Methods

NS_DEV_DOCFOR:objc_method:[Scroller-acceptsFirstMouse];,acceptsFirstMouse

- (BOOL)acceptsFirstMouse

Overrides inherited methods to ensure that the Scroller will receive the mouse-down event that made its window the key window.  Returns YES.

NS_DEV_DOCFOR:objc_method:[Scroller-action];,action

- (SEL)action

Returns the action of the ScrollerÐin other words, the selector for the method the Scroller will invoke when it receives a mouse-down event.

See also:  - target, - setAction:

NS_DEV_DOCFOR:objc_method:[Scroller-awake];,awake

- awake

Overrides Object's awake method to perform additional initialization.  After a Scroller has been read from an archive file, it will receive this message.  You should not invoke this method directly.  Returns self.

See also:  - read

NS_DEV_DOCFOR:objc_method:[Scroller-calcRect:forPart:];,calcRect:forPart:

- (NXRect *)calcRect:(NXRect *)aRect forPart:(int)partCode

Calculates the rectangle (in the Scroller's drawing coordinates) that encloses a particular part of the Scroller.  This rectangle is returned in aRect.  partCode is NX_DECPAGE, NX_KNOB, NX_INCPAGE, NX_DECLINE, NX_INCLINE, or NX_KNOBSLOT.  This method is useful if you override the drawArrow:: or drawKnob method.  Returns aRect (the pointer you passed it).

See also:  - drawArrow::, - drawKnob

NS_DEV_DOCFOR:objc_method:[Scroller-checkSpaceForParts];,checkSpaceForParts

- checkSpaceForParts

Checks to see if there is enough room in the Scroller to display the knob and buttons and sets sFlags.partsUsable to one of the following values:

Value	Meaning

NX_SCROLLERNOPARTS	Scroller has no usable parts, only the bar.
NX_SCROLLERONLYARROWS	Scroller has only scroll buttons.
NX_SCROLLERALLPARTS	Scroller has all parts.

This method is used by sizeTo::; you should not invoke this method yourself.  Returns self.

See also:  - sizeTo::

NS_DEV_DOCFOR:objc_method:[Scroller-drawArrow::];,drawArrow::

- drawArrow:(BOOL)upOrLeft :(BOOL)highlight

Draws a scroll button.  If upOrLeft is NO, this method draws the down or right scroll button (NX_INCLINE), depending on whether the Scroller is oriented vertically or horizontally.  If upOrLeft is YES, this method draws the up or left scroll button (NX_DECLINE).  The highlight state is determined by highlight.  If highlight is YES, the button is drawn highlighted, otherwise it's drawn normally.  This method is invoked by drawSelf:: and mouse-down events. It's a public method so that you can override it; you should not invoke it directly.  Returns self.

See also:  - drawKnob, - calcRect:forPart:

NS_DEV_DOCFOR:objc_method:[Scroller-drawKnob];,drawKnob

- drawKnob

Draws the knob.  Don't send this message directly; it's invoked by drawSelf:: and mouse-down events.  Returns self.

See also:  - drawArrow::, - calcRect:forPart:

NS_DEV_DOCFOR:objc_method:[Scroller-drawParts];,drawParts

- drawParts

This method caches images for the various graphic entities composing the Scroller.  It's invoked only once by the first of either initFrame: or awake.  You may want to override this method if you alter the look of the Scroller, but you should not invoke it directly.  Returns self.

NS_DEV_DOCFOR:objc_method:[Scroller-drawSelf::];,drawSelf::

- drawSelf:(const NXRect *)rects :(int)rectCount

This method draws the Scroller.  It's used by the display methods, and you should not invoke it directly.  rects is an array of rectangles that need to be covered, with the first one being the union of the subsequent rectangles.  rectCount is the number of elements in this array.  Returns self.

See also:  - display::: (View)

NS_DEV_DOCFOR:objc_method:[Scroller-floatValue];,floatValue

- (float)floatValue

Returns the position of the knob, a value in range 0.0 to 1.0.  A value of  0.0 indicates that the knob is at the top or left position within the bar, depending on the Scroller's orientation.

See also:  - setFloatValue::

NS_DEV_DOCFOR:objc_method:[Scroller-highlight:];,highlight:

- highlight:(BOOL)flag

This method highlights or unhighlights the scroll button that the user clicked on.  The Scroller invokes this method while tracking the mouse, and you should not invoke it directly.  If flag is YES, the button is drawn highlighted, otherwise it's drawn normally.  Returns self.

See also:  - drawArrow::

NS_DEV_DOCFOR:objc_method:[Scroller-hitPart];,hitPart

- (int)hitPart

Returns the part of the Scroller that is causing the current action, typically the part that received a mouse-down event.  See the Scroller class description for possible values.  This method is typically invoked by the ScrollView to determine what action to take when the ScrollView receives an action message from the Scroller.

See also:  - action

NS_DEV_DOCFOR:objc_method:[Scroller-initFrame:];,initFrame:

- initFrame:(const NXRect *)frameRect

Initializes a newly allocated Scroller with frame frameRect, which cannot be NULL.  If frameRect's width is greater than its height, a horizontal Scroller is created; otherwise, a vertical Scroller is created.  The Scroller is initially disabled.  If the Scroller is a subview of a ScrollView, its width and height are reset automatically by the ScrollView's tile method; in this case, the width of vertical Scrollers and the height of horizontal Scrollers are set to NX_SCROLLERWIDTH.  This method is the designated initializer for the Scroller class.  Returns self.

See also:  - setEnabled: (Control), - tile (ScrollView)

NS_DEV_DOCFOR:objc_method:[Scroller-mouseDown:];,mouseDown:

- mouseDown:(NXEvent *)theEvent

This method acts as a dispatcher when a mouse-down event occurs in the Scroller.  It determines what part of the Scroller was clicked, and invokes the appropriate methods (such as trackKnob: or trackScrollButtons:).  You should not invoke this method directly.  Returns self.

NS_DEV_DOCFOR:objc_method:[Scroller-read:];,read:

- read:(NXTypedStream *)stream

Reads the Scroller from the typed stream stream, and sets all aspects of its state.  Returns self.

See also:  - write:, - awake

NS_DEV_DOCFOR:objc_method:[Scroller-setAction:];,setAction:

- setAction:(SEL)aSelector

Sets the action of the Scroller.  When the user manipulates the Scroller, the Scroller sends its action message to its target, which (if it's a ScrollView) will then query the Scroller to determine how to respond.  Returns self.

See also:  - setTarget:, - action

NS_DEV_DOCFOR:objc_method:[Scroller-setArrowsPosition:];,setArrowsPosition:

- setArrowsPosition:(int)where

Sets the location of the scroll buttons within the Scroller to where, or inhibits their display, as follows:

Value	Meaning

NX_SCROLLARROWSMAXEND	Buttons at bottom or right
NX_SCROLLARROWSMINEND	Buttons at top or left
NX_SCROLLARROWSNONE	No buttons

Returns self.

NS_DEV_DOCFOR:objc_method:[Scroller-setFloatValue:];,setFloatValue:

- setFloatValue:(float)aFloat

Sets the position of the knob to aFloat, which is a value between 0.0 and 1.0.  This method is the same as setFloatValue:: except it doesn't change the size of the knob.  Returns self.

See also:  - setFloatValue::, - floatValue

NS_DEV_DOCFOR:objc_method:[Scroller-setFloatValue::];,setFloatValue::

- setFloatValue:(float)aFloat :(float)knobProportion

Sets the position and size of the knob.  Sets the position within the bar to aFloat, which is a value between 0.0 and 1.0.  A value of 0.0 positions and displays the knob at the top or left of the bar, depending on the orientation of the Scroller.  The size of the knob is determined by knobProportion, which is a value between 0.0 and 1.0.  A value of 0.0 sets the knob to a predefined minimum size, and a value of 1.0 makes the knob fill the bar.  Returns self.

See also:  - setFloatValue:, - floatValue

NS_DEV_DOCFOR:objc_method:[Scroller-setTarget:];,setTarget:

- setTarget:anObject

Sets the target of the Scroller to anObject.  The Scroller's target receives the action message set by setAction: when the user manipulates the Scroller.  Returns self.

See also:  - target, - setAction:

NS_DEV_DOCFOR:objc_method:[Scroller-sizeTo::];,sizeTo::

- sizeTo:(NXCoord)width :(NXCoord)height

Overrides the default View method so the Scroller can check which parts can be drawn.  This method is typically invoked by tile (ScrollView), which sets the Scroller to a constant width (or height, if the Scroller is horizontal) of NX_SCROLLERWIDTH.  Returns self.

See also:  - checkSpaceForParts, - tile (ScrollView)

NS_DEV_DOCFOR:objc_method:[Scroller-target];,target

- target

Returns the Scroller's target.

See also:  - setTarget:, - action

NS_DEV_DOCFOR:objc_method:[Scroller-testPart:];,testPart:

- (int)testPart:(const NXPoint *)thePoint

Returns the part of the Scroller that lies under thePoint.  See the Scroller class description for possible values.

NS_DEV_DOCFOR:objc_method:[Scroller-trackKnob:];,trackKnob:

- trackKnob:(NXEvent *)theEvent

Tracks the knob and sends action messages to the Scroller's target.  This method is invoked when the Scroller receives a mouse-down event in the knob.  You should not invoke this method directly.  Returns self.

See also:  - mouseDown:, - action, - target

NS_DEV_DOCFOR:objc_method:[Scroller-trackScrollButtons:];,trackScrollButtons:

- trackScrollButtons:(NXEvent *)theEvent

Tracks the scroll buttons and sends action messages to the Scroller's target.  This method is invoked when the Scroller receives a mouse-down event in a scroll button.  You should not invoke this method directly.  Returns self.

See also:  - mouseDown:, - action, - target

NS_DEV_DOCFOR:objc_method:[Scroller-write:];,write:

- write:(NXTypedStream *)stream

Writes the Scroller to the typed stream stream, saving all aspects of its state.  Returns self.

See also:  - read: